feat(manifest): authoritative agent-bundle.manifest.json v2 — consumers read the composite root through the manifest (#592 step 3, #555 W2/S3) - #604

Implements #592 step 3 — the authoritative manifest together with #555 W2/S3 — consumers read the composite root through the manifest. Design comment: #592 (comment). Owner guidance from the 08:30 review is implemented, not noted — see "Owner review (08:30)" below.

What changes

agent-bundle.manifest.json is manifestVersion: 2: closed keys, canonical stableJson bytes, every path root-relative POSIX, and it is serialized from the compiler's own IR (NormalizedPlugin → CompiledRouteGraph → TargetArtifactPlans) rather than reconstructed. The host documents (.claude-plugin/plugin.json, .codex-plugin/*, .cursor-plugin/plugin.json, .mcp.json, hooks/hooks.json, marketplace catalogs) are projections the manifest points at; nothing reads them for identity any more.

Public contract (durable)

Compiler record (operational, versioned separately)

compiler.recordVersion: 1 with producer{name,version}, project{configPath,configDigest,modelDigest,revision,sourceInputs[],packageName?,packageVersion?}, provenance[]{path,sourceInputs[]} (paths exactly match files[]), adapters[]{host,adapterRevision,observedVersion,schemas[]}, agentSkills, validation. Changing anything here never changes the public contract; manifestVersion and recordVersion move independently.

targets[] → projections[]; validation.targets[] → validation.projections[]; files[].sourceInputs → compiler.provenance[]; producer/project/agentSkills/validation moved under compiler. The agent-bundle.hooks.json sidecar is gone (build/hook-index.ts deleted); hook rows are executables.hooks[].

Shipped schema

packages/agent-bundle/schemas/agent-bundle.manifest.schema.json (draft 2020-12, additionalProperties: false everywhere, in files), exported as artifactManifestSchema and validateArtifactManifestSchema from agent-bundle and agent-bundle/api, beside readArtifactManifest, parseArtifactManifest, artifactManifestName, artifactManifestVersion, artifactCompilerRecordVersion. tests/manifest-schema.test.ts proves the writer's output validates, the schema's keys agree with the TypeScript type, and closed-key extras are rejected by both.

Consumers rewired (probing deleted in the same change)

Diagnostics (docs/diagnostics.md)

• AB6010 now also judges adapter identity: projections[].builtInHost must equal TargetRegistry.builtInHost(host) besides revision/version/schemas.
• AB6018 is judged from executables.hooks[], not the deleted sidecar.
• AB7001 sources from the manifest: missing or non-canonical manifest, no projection whose builtInHost is the host, missing documents.plugin, pointer to a file the root lacks, a files[] row missing or digest-mismatched, unsafe Cursor name, Claude/Codex without marketplace.name. doctor --from reports the same AB7001 (with a Doctor recovery) instead of folding it into AB7306; AB7306 remains for non-diagnostic failures.
• AB6039/AB6040 existed in an earlier revision as drift detectors between the manifest and host documents; removed per the 08:30 review — the adapter runtime/hook contracts are the single source for documents.mcp/documents.hooks, so there is no second source to drift.

Owner review (08:30)

1. Serialized from IR, no drift detector. manifestFor takes the CompiledRouteGraph, the NormalizedPlugin, the selected TargetArtifactPlans and the registry contracts; documents.mcp/documents.hooks come from registry.mcpRuntime(host).manifestPath / registry.hookContract(host).manifestPath. AB6039/AB6040 deleted.
2. Operational metadata separated. compiler record with its own recordVersion (above).
3. Relocatable paths. core/paths.ts isRelocatablePosixPath gates every path field in writer and parser (must be a safe relative POSIX path); tests/manifest-relocatable.test.ts builds a four-host fixture with hooks, scripts, a CLI bin, a compiled MCP server, an MCP App and web, asserts no machine path appears in the bytes, every pointer is a files[] row, moves the root to another directory, and re-runs validateArtifact, readArtifactManifest, readBundleIdentity (three hosts) and the MCP pointer resolution against the moved root — byte-identical manifest, same answers. Forged absolute executables.mcpServers[].entry.path and web.apps[].entry are rejected.
4. Copied-artifact proof. Below.
5. Inline threads. None were left on the PR; the review body's points are the five above.

cargo-hauler proof (#107 §1) — copied artifact, no source, no node_modules

Full report and traces: /tmp/592-proof3/report.md, /tmp/592-proof3/{out,traces}/. Head proved: 464f30ca8 (the reviewer fixes after it touch doctor error codes, mcp run argument order and tests only). Packed from a detached worktree: agent-bundle-0.1.0.tgz 164cd05d…111a (3,403,441 B), agent-bundle-runtime-0.0.0.tgz 25e9cd0b…9343, rsc-markdown-stream-0.1.0.tgz 5c154ac6…01fa. Scratch cargo-hauler at /tmp/592-proof3/hauler (source checkout untouched), pnpm-workspace.yaml overrides → the tarballs, pnpm install + agent-bundle build → composite artifact/ (no artifact/<host>), validate --artifact 0 errors, Claude plugin validate loaded.

Manifest: manifestVersion 2, compiler.recordVersion 1, application cargo-hauler@0.6.0, projections claude/codex/cursor/portable, 37 files[], executables.bins[0] bin/cargo-hauler.mjs + bin/cargo-hauler-flight.mjs worker, one compiled MCP server hauler with App hauler/dashboard, 12 hooks.

cp -r artifact /tmp/592-proof3/root-… then test ! -e for agent-bundle.config.ts, src, node_modules, package.json under the root and the cwd. Every command traced with strace -f (openat/statx/getdents64/execve/clone), filtered to the copied root:

Corrupted copies (/tmp/592-proof3/hauler-corrupt): deleting projections[cursor].builtInHost → AB7001 … built for projections [claude, codex, cursor, portable]; none is the shipped cursor adapter; garbled JSON → AB7001 … not a valid canonical artifact manifest: Artifact manifest is not valid JSON.; documents.plugin → does-not-exist.json → AB7001 … names "does-not-exist.json", which is not a manifest file. — on both doctor and install --json.

Residual filesystem access, stated plainly:

• mcp list|invoke and serve-app still run validateArtifact before launching — the pre-existing tamper gate that compares the tree against files[] (that is the getdents64 in the table). It is not probing for structure; every launch decision comes from the manifest. Narrowing it to the executed rows is a follow-up, not this PR.
• doctor stats fixed names (state, .env, .env.local; for Claude .lsp.json, monitors/monitors.json, settings.json) — operator data and Claude's project layout, not artifact structure; and the host CLIs it spawns (claude plugin list) walk the root themselves.
• Workbench is project-bound (dev server over a project root); its artifacts page renders the same ApplicationExplorer that inspect --artifact prints, from the manifest only (tests/application-explorer.test.ts, packages/workbench/tests/examples-real.e2e.test.ts).
• cargo-hauler's own tests/version-consistency.test.ts still opens artifact/cursor/.cursor-plugin/plugin.json and fails with ENOENT — the consumer change meta-framework: execution plan and sequencing #107 §1 asks for; not modified here.

Absorbed from main after the owner's go (#616 / #630 / #629)

Merged origin/main twice (7769b21fc: #629 + #630; 472d64d1a: #616 + #628). Nothing on the branch keeps a second copy:

• feat(routes): CLI surface projections of MCP tools — colocated <tool>.cli.ts, mapInput, AB4843–AB4845 (#596) #616 CLI projections — routes.cli.commands[].projection{module,mapInput,defaults?,relaxed?} and options[].aliases come from CompiledCliProjection/CompiledCliOption via build/manifest-routes.ts; AB4843–AB4845 stay compile-time (the compiler is the only judge; the manifest records the result). dev/routes/route-manifest.ts now aliases the manifest's CLI types instead of declaring its own copies. Schema, parser, tests/manifest-schema.test.ts parity rules, tests/cli-routes-build.test.ts (built artifact carries the projection), en/zh reference updated; "Reserved keys" no longer lists projection.
• feat(config): definePrebuilt and payload runtimeDependencies as AB7014 evidence (#619 step 4) #630 definePrebuilt / runtimeDependencies — distribution.payloads[] is serialized from NormalizedPlugin.payloads, filtered to the selected hosts and sorted; the parser requires each payload directory to hold at least one prebuilt files[] row and payloads[].hosts to name declared projections. Test: tests/prebuilt-payload.test.ts (records a payload only for the selected hosts it targets …).
• fix(564): port the #620 review follow-ups from the merged branch — declared-projection web launch, identity-keyed sessions, opening-tool policy, out-of-artifact web state #628 web launch selection — web-host/manifest.ts readWebManifestDocument read the v1 targets[].name list for the declared projections; on manifest v2 that is projections[].host, so the dev /web route saw no launchable projection (CI integration-1: dev-web-host-routes.test.ts 404). Reader and web-host-routes-unit.test.ts fixture moved to the v2 shape; no v1 fallback kept.
• feat(workbench): application explorer — shell, Application tree, route workspace, one invocation API, page cuts (#600 PR 1) #629 Workbench application explorer — consumes ArtifactInspection (which the inspection service derives from the manifest); ArtifactInspectionMcpServer gained transport so the Application tree keeps labelling servers by transport while kind means command|compiled|remote. Workbench validator (isMcpServer) and fixtures updated; application-tree-model.test.ts asserts the label.

Owner audit (17:11) — contract table

Each row done on the integrated head; the fresh reviewer passes below cover the result.

Merged origin/main through #636, #638 (compile evidence record — admitted as root metadata in validate-artifact.ts; the hook-index half of that merge stays deleted), #640 and #642.

Deslop

Deslop: gpt-5.6-sol-medium, 11 edits proposed / 9 applied on the pre-merge diff (365939501, 0e34c653a; two reverted: the "Reserved keys" sections in the en/zh manifest reference, which the brief requires) + 1 edit on the post-merge delta (ff3d3efc0) + 1 edit on the #616/#630 absorption delta (59dbb1ee5; the other proposals touched main's own comments outside the delta and were not applied) + 2 edits on the 17:11 contract-table delta (6b10803f2: temp-home cleanup in prebuilt-payload.test.ts) + 2 edits on the #638/#642 merge delta (2387162ac: two restating comments) + 2 edits on the P2 reader/reindex delta (c78bfc8d2) + 5 file-level edits on the post-74ccb99 delta after the #634 merge (bb241b281: 12 restating comments in build.ts, build-compose.test.ts, prebuilt-payload.test.ts, web-manifest.test.ts; three non-null assertions in parseRoutes replaced by a type-narrowing filter) + 10 edits on the Pass 8 fix delta (1db705bc5, Sol: 13 proposed, 3 reverted where the comment gave the reason rather than restating the code). Changeset condensed by hand.

Self-review

Reviewer: gpt-5.6-sol-medium (author lanes: Fable/Sol/Grok; integrator Fable).

Pass 1 (on 464f30ca8) — 4 findings, all fixed:

1. tests/preflight-artifact-graph.test.ts still read agent-bundle.hooks.json → reads manifest.executables.hooks (6f69911f2).
2. doctor --from folded every AB7001 into AB7306, contradicting docs/changeset → malformedBundle preserves DiagnosticError diagnostics; AB7306 only for non-diagnostic errors; test updated (ff3d3efc0).
3. mcp run rebuilt the launch as [manifestEntry, ...hostArgs.slice(1)], wrong for adapters that put flags first or use the entry as command → the host document's line is used verbatim; a document that skips the compiled entry is already refused at build (AB6017), so no runtime re-check (ff3d3efc0, fe49a137a).
4. tests/manifest-relocatable.test.ts omitted web.apps[].entry → fixture gained an MCP App + web; absolute and unlisted web entries asserted rejected (ff3d3efc0).

Pass 2 (on 60148f923) — 5 findings, 4 fixed, 1 dismissed (fe49a137a):

1. Schema relativePath accepted C:escape while the parser rejects it → (?![A-Za-z]:) lookahead added; parity case in tests/manifest-schema.test.ts.
2. No test covered a host launch line with arguments before and after the entry → tests/build-compose.test.ts launches a synthetic adapter whose document is --enable-source-maps <entry> --stdio and asserts the exact sequence, and asserts the build refuses (AB6017) a document that skips the entry.
3. The non-DiagnosticError AB7306 fallback lost its test → tests/doctor.test.ts makes .cursor-plugin a regular file (ENOTDIR on the pointer check) and asserts AB7306 with no AB7001.
4. AB7306 had no row in docs/diagnostics.md → "Read-only Doctor bundle resolution (AB7306)" section added; coverage check green.
5. cli.ts inspect --artifact uses await import('./api.ts') — dismissed: that is the module's documented policy (header comment, lines 7–16) and every other action in the file does the same so --help/--version do not load the product graph.

Pass 3 (merge delta vs origin/main after absorbing #616/#630/#629, on 59dbb1ee5) — 5 findings, all fixed (2d5eb053a), reviewer re-run: "No findings":

1. manifestPayloads host filtering untested → tests/prebuilt-payload.test.ts builds with targets: ['claude', 'portable'] against payloads targeting codex and claude, asserts only runtime is recorded with hosts: ['claude'] and no app/ rows are staged.
2. Workbench Application tree used ArtifactInspectionMcpServer.kind as the transport label after kind changed meaning → transport added to the inspection row, service, Workbench validator, model, and fixtures.
3. distribution.payloads[<name>] location string → distribution.payloads[<index>].name, matching the rest of the parser.
4. docs/diagnostics.md omitted defaults? from the projection field list → added.
5. {@link CompiledCliProjection} in route-manifest.ts/manifest.ts relies on TypeDoc's project-wide resolution — dismissed: pnpm docs:site:build resolves it (0 broken links) and the file's other links use the same form.

Pass 4 (contract-table delta, on 74ccb996b) — 5 findings, all fixed (17edaf120, 6b10803f2):

1. mcp run's no-host-document fallback dropped the manifest launch args/env → built from row.launch with expandLaunchTokens (shared with resolveWebLaunch), artifact arguments under the root, env under the durable root.
2. web-host/manifest.ts never checked manifestVersion → requires 2; rejection tests for undefined/1/3/'2'.
3. Combined-proof install/replace/uninstall assertions matched prefixes → pin the whole first stdout line (destination, content hashes, for cursor (local mode)).
4. No test passed prebuilt args/env through the launch record and web launcher → prebuilt-payload.test.ts adds a server with literal/artifact args and tokenized env, asserts the record and the resolved launch (state under home, not the artifact).
5. Schema descriptions said launch/web servers are compiled-only → say compiled or prebuilt.

Pass 5 (fresh, integrated result incl. #640/#636, on 6b10803f2) — 2 findings, both fixed (9b8ce27e9, 66ac3a7bf), reviewer re-run: "No findings" on code, docs precision only:

1. The fallback in (4.1) did not inject AGENT_BUNDLE_PLUGIN_ROOT, so a generated server could derive state from the artifact → anchored on the durable root; build-compose.test.ts reaches the fallback through a registry whose reader aliases server names (AB6017 still holds) and asserts the anchor.
2. Reference prose said every reader enforces canonical bytes and the top level has exactly nine keys → "Lean reader" row names the one non-parser consumer (<plugin> web support) and what it checks; "nine required keys plus optional web"; Versioning notes the lean reader rejects the version mismatch first.

Pass 6 (#638/#642 merge delta, on 93fa0e1c9) — 1 finding, fixed (2387162ac): the doctor row claimed a manifest-less root always gets the derived state root; it falls back to an inherited AGENT_BUNDLE_STATE_ROOT first. Verified by the reviewer: readArtifactManifest never throws on arbitrary directories, no import cycle from install/ to build/manifest-file.ts, install copies the manifest so the three callers see it, the manifest is excluded from the ownership walk, no live reference to the hook index remains.

Pass 7 (owner P2 + evidence items, on d31aca73a…d1018dedb) — 7 findings, 6 fixed, 1 dismissed:

1. Lean reader did not check launch.entry/worker/artifact args against files[] → parseFilePaths + requireLaunchFiles shared with the full parser (8fa261880).
2. parseProjectionHosts/parseServerLaunches validate only the slices the lean reader launches from — dismissed by design, documented in the "Lean reader" row: it refuses rather than filters those slices and ignores the rest.
3. copyInventoryFiles verified the source and copied without re-hashing (TOCTOU) → the copy is re-measured and refused when it is not the verified inventory (8fa261880; test in install.test.ts).
4. "Written once" contradicted reindexArtifactManifest → reference rows say reindexing re-measures non-compiled rows and refuses bundle rows and the compile evidence record (8fa261880).
5. A prebuilt payload named state was indexed by the manifest but skipped by treeInventory, so a valid artifact failed the copy hash → state/ is reserved everywhere: AB4741 for the payload, both parsers and the schema refuse files[] rows under it in any letter case (c97457521).
6. The lean reader still admitted launches under state/ → one parseArtifactFilePath used by both readers (d1018dedb).
7. .agent-bundle-install.json passed the parser but treeInventory rejects it → the same rule reserves the receipt entry (d1018dedb).

Pass 8 (fresh, rebased result through #634/#646, on bb241b281; change-risk-reviewer could not start over tracedecay transport, fell back to generalPurpose on Sol) — 3 findings, all fixed (1af72fec00, 66c72f458):

1. requireLaunchFiles checked path membership only: a compiled server's launch.entry could name a generated/copy row (bytes no compile evidence describes) and two servers' records could be swapped without any check against the host documents → (a) both readers require the entry to be the row its server kind starts (bundle for compiled, prebuilt for prebuilt) and the worker a bundle row (parseFileKinds, shared artifactManifestFileKinds); (b) validateMcpCoherence holds every host document to the launch records projected to its host: every launchable manifest server for the target must appear in the document under the same name (validateDeclaredServersPresent), and each stdio document server's artifact-local paths must include its record's entry and artifact arguments (validateLaunchAgreement, a subset check so a ./payload/file literal the adapter resolves artifact-locally is not rejected), else AB6017. With drift refused at validation, mcp run's manifest-only fallback became unreachable for any validated root and is deleted (66c72f458): the host document is required and is the launch line. Tests: web-manifest.test.ts, manifest.test.ts (wrong-kind entry, prebuilt at a bundle), artifact-validator.test.ts (swapped record → AB6017; renamed server → AB6017; agreeing record with an artifact-local literal → none), build-compose.test.ts (aliased document names → mcp run refuses with AB6017, nothing spawned).
2. manifestInventory compared sha256 only, so a post-build chmod on an indexed row installed as authoritative → uses matchesManifestFile (bytes, mode, path, digest) like validate-artifact; install.test.ts asserts AB7001 on an executable bit the row does not declare. Test fixtures (support/install-fixture.ts, public-api-packed.test.ts) now record mode and bundle kinds the way the compiler does.
3. The manifest path rule admitted names the receipt reader rejects (NUL, CON.txt, a:b, trailing dot/space, control characters), so a valid manifest could be uninstallable → one isPortablePathSegment in core/paths.ts used by isRelocatablePosixPath (both parsers) and isReceiptPath; the schema's relativePath pattern mirrors it; five parity rules added to manifest-schema.test.ts.

Pass 9 (re-run after the Pass 8 fixes, on 1db705bc52, Sol) — 3 must-fix, 2 should-fix, all fixed (1ee3cffae5):

1. Agreement compared an unordered set, so node payload/bootstrap.mjs mcp/server.mjs passed while Node ran the bootstrap → validateLaunchAgreement takes the document's artifact-local paths in launch order: the first must be the record's entry, the record's artifact arguments must follow it as an ordered subsequence; flags and literals may interleave.
2. A non-stdio document server with the same name as a launchable record skipped agreement and failed only in mcp run → AB6017 when the document reaches a launchable record over another transport.
3. Validation read the document at runtime.manifestPath while mcp run reads projections[host].documents.mcp, so a manifest missing the pointer validated and then failed to launch → the pointer must equal the runtime's document path whenever either exists (AB6017); artifact-inspection-service.test.ts's pointerless-host case now asserts refusal at publish.
4. docs/diagnostics.md AB6017 said "exactly" → describes the ordered rule, the pointer, and the transport case.
5. Schema parity covered one device name → con.txt, COM¹.log, lpt³ rejected by both; COM10.log, console.txt, nulled/index.json, lpt.txt accepted by both.
   Re-run on 1ee3cffae5 (Sol): no findings.

Gates

On 1ee3cffae5 (after merging origin/main through #634/#646): pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit green (4228 passed); the touched integration suites green (234 passed: combined proof, host install proofs, prebuilt payload, web command, compile evidence, artifact validator, dev host install, build, build-compose, install, doctor, uninstall, dev web-host routes, package build); pnpm test:packed (38) green; pnpm docs:site:build green (parity ok). Earlier on 66c72f458: pnpm build && pnpm typecheck && pnpm lint && pnpm test:unit green (4221 passed); the touched integration suites green (209 passed on 1af72fec00: combined proof, host install proofs, prebuilt payload, web command, compile evidence, artifact validator, dev host install, build, build-compose; 172 passed on 66c72f458: build-compose, package-build, artifact validator, combined proof); pnpm test:packed (full packed pool, 37) green; pnpm docs:site:build green (0 broken links, parity ok). Full pnpm test:integration:run last ran green on 2387162ac. Earlier heads: e91b06825, 565bd77e5.

Hand-offs (posted on #555 and #592 at merge)

• S4 (npm root): distribution.channels already carries 'npm' when compiler.project.packageName is set; add the npm-specific pointers under distribution (closed keys → schema + parseDistribution + website/docs/*/reference/artifact-manifest.mdx), never under projections[].
• S5 (INSTALL.md / install.mjs): distribution.install.instructions / .script are the pointers; AB6023/AB6024 already require the files per builtInHosts(selected). Author the contents; keep them files[] rows (the writer indexes them automatically). The generated install.mjs (install/surface.ts) still reads .cursor-plugin/plugin.json and probes .cursor-plugin/mcp.json/mcp.json for runtimeStateRoots (fix: manage derived state across lifecycle #642) because it also installs Agent Plugins packs that have no artifact manifest; when S5 rewrites it, read agent-bundle.manifest.json (projections[cursor].documents.{plugin,mcp}) first and keep the probe only for manifest-less packs.
• Step 4 (shared compiler policy): compiler is the seam — add policy inputs (cache keys, tool versions, timings) there and bump recordVersion only; manifestVersion stays 2. reindexArtifactManifest is the one path that rewrites a manifest outside build.